Skip to main content

4. Authentication

4.1 Introduction​

The getJWT is responsible for obtaining a JSON Web Token (JWT) by making a call to an DVLA AUTH API. It is primarily used to authenticate the incoming requests for licence checking to the DVLA ADD API.

DVLA Authentication URL​

https://driver-vehicle-licensing.api.gov.uk/thirdparty-access/v1/authenticate

4.2 Functionality​

  1. After successfully passing all the checks in the licencePreCheck middleware, the getJWT middleware extracts essential information from the incoming request, including the leaseId, driverId and driver details.
  2. If running in a testing environment, it provides a mock JWT for testing purposes and proceeds to the next middleware.
  3. Constructs a payload along with headers as shown below and sends an HTTP POST request to an authentication API to obtain a JWT.
{
  "userName": "********",
  "password": "********"
}
{
  'Content-Type': 'application/json',
  Accept: 'application/json',
}
  1. Logs information related to the API call, including request payload and response details.
  2. Upon successful API response, stores the obtained JWT in the request object for future use.
  3. Attaches an updateLog function to the request object for logging purposes.
  4. If an error occurs during the API call, it logs the error and passes it to the next middleware for error handling.

4.3 API Responses​

4.3.1 Positive Response​

A successful request should return a JSON response containing the JWT string required to be passed into subsequent API calls.

Example Response:

{
    "id-token": "auth-token"
}

4.3.2 Negative Responses​

  • Bad Request: If the request payload is malformed or missing required fields, the API may respond with a 400 Bad Request error.

  • Unauthorized: If the provided credentials are invalid or the user has tried to authenticate before changing their temporary password, the API may respond with a 401 Unauthorized error.

4.4 Logging​

4.4.1 Logging the request​

The updateLog function is called to log the following:

  • level: Set to 'info' to indicate an informational log.
  • requestForJWT: Logs the details of the API request, including the following sub-parameters:
    • payload: Contains the sliced username and password being sent in the API request.
    • url: Specifies the URL of the DVLA_AUTH API.
    • message: Describes the purpose of the log entry, by specifying "calling AUTHENTICATION API with payload".
  • driverDetails: Contains information about the driver for context.

4.4.2 Logging the response​

The updateLog function is called to log the following:

  • level: Set to 'info' to indicate an informational log.
  • responseForJWT: Logs the details of the API response, including the following sub-parameters:
    • path: Logs the path of the API request.
    • message: Describes the log message, in this case, "AUTHENTICATION API call successful".
    • response data along with the jwt token.
  • driverDetails: Contains information about the driver for context

4.5 Configuration​

  1. Environment variables for API credentials:
  • DVLA_USERNAME
  • DVLA_PASSWORD
  1. Environment variable for URL:
  • DVLA_AUTH_URL

Status: Draft (Pending Review)
Category: Protected
Authored By: Sohan on Oct 05, 2023